home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / specs / hdfspecs.lha / HDFSpecs.ch4 < prev    next >
Text File  |  1992-03-04  |  7KB  |  184 lines
  1. 4.1    NCSA HDF Specifications
  2.  
  3. HDF Conventions    4.1
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. March 1989
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13. 4.1    NCSA HDF Specifications
  14.  
  15. HDF Conventions    4.1
  16.  
  17. National Center for Supercomputing Applications
  18.  
  19. March 1989
  20.  
  21.                                                                 
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29. Chapter 4    HDF Conventions
  30.  
  31.  
  32.  
  33. Chapter Overview
  34. Byte Order
  35. Naming and Assigning Tags
  36. Using Reference Numbers to Organize Data 
  37. Objects
  38. Multiple References and File Compaction
  39.  
  40. Chapter Overview
  41.  
  42. The specification of HDF described in the previous chapter is not 
  43. sufficient to guarantee its success. With a general structure such 
  44. as HDF to work with, you may be tempted to create overly clever, 
  45. obscure, and complex files, defeating the purpose behind the design 
  46. of HDF╤to facilitate the interchange of data among differing 
  47. applications, programs, and computer systems. To guard against 
  48. these problems, a number of guidelines on the use of HDF are 
  49. provided:  some are implicit in the discussions in other sections of 
  50. this document and others are presented in the NCSA HDF manual. 
  51. Additional guidelines not covered elsewhere are introduced in this 
  52. section.
  53.  
  54.  
  55. Byte Order
  56.  
  57. The byte-ordering of data stored in memory and on files varies 
  58. from machine to machine.  It is important to address this 
  59. possibility in any software that processes data from files that might 
  60. have visited more than one machine.
  61.  
  62. In most cases, the existence of "byte-swapped" data can be detected 
  63. by examining the  Machine Type (MT) tag, which is described in 
  64. Appendix A.  Unfortunately, a program cannot look at the MT 
  65. until it has opened an HDF file and looked at the header, so it is 
  66. important that the byte order of the header be the same, no matter 
  67. what machine is used to create an HDF file.  Therefore, to 
  68. maintain machine portability when developing software for 
  69. machines that swap bytes, you should make sure that the characters 
  70. are read and written in the exact order specified (i.e., ^N^C^S^A).
  71.  
  72.  
  73. Naming and Assigning Tags
  74.  
  75. Tags that are to be made available to a general population of HDF 
  76. users should be assigned and controlled by NCSA. Tags of this type 
  77. are given numbers in the range 8,000╨15,999. If you have an 
  78. application that fits this criterion, contact NCSA at the address 
  79. listed on the README page at the beginning of this manual and 
  80. specify the tags you would like. For each tag, your specifications 
  81. should include a suggested name, information about the type and 
  82. structure of the data that the tag will refer to, and information about 
  83. how the tag will be used. Your specifications should be similar to 
  84. those contained in Appendix A. NCSA will assign you a set of tags 
  85. for your application and include your tag descriptions in its 
  86. documentation.
  87.  
  88. Tags in the range 16,000╨32,000 are user-definable. That is, you 
  89. can assign them for any private application. Of course, if you use 
  90. tags in this range you need to be aware that they may conflict with 
  91. other people's private tags.
  92.  
  93. Using Reference Numbers to Organize Data Objects
  94.  
  95. Reference numbers distinguish between one data object and others 
  96. with the same tag. It is often tempting to assign meaning to 
  97. reference numbers beyond this distinction. Such uses of reference 
  98. numbers are generally discouraged because most HDF software 
  99. assumes that reference numbers can be chosen or assigned in any 
  100. order, as long as all tag/ref combinations in a file remain unique.
  101.  
  102. On the other hand, in some situations reference number can be 
  103. used easily and effectively to add meaning to a file╤for instance, 
  104. to provide informal grouping and ordering of data objects. For 
  105. example, suppose you want to create a movie out of the images in an 
  106. HDF file. The images need to be ordered in some way and each 
  107. image needs to be associated with other data objects. In such cases, 
  108. you should refer to the following rules to assign reference 
  109. numbers, especially among sets of tags that are required to go 
  110. together.
  111.  
  112. 1.    Assign reference numbers in increasing order.
  113.  
  114. 2.    When a companion object is required (for example, image 
  115. dimension is needed for images), use the object with the current 
  116. reference number. If none exists, use the object with the next 
  117. lowest reference number.
  118.  
  119. 3.    When there are several combinations, cycle through reference 
  120. numbers for each tag type in ascending order in all 
  121. combinations that do not break the order.
  122.  
  123. For example, suppose the following data identifiers are in a file:  
  124. IP8[1], ID8[1], RI8[1], RI8[2], IP8[2], IP8[3], IP8[4], RI8[4], RI8[10], 
  125. DIL[1], DIL[10]. Objects in the file should be grouped in the order 
  126. shown in Table 4.1.
  127.  
  128.  
  129. Table 4.1    Sample Grouping of 
  130. Data Objects in an 
  131. HDF File
  132. IP8    ID8    RI8    DIL
  133. 1    1    1    1        palette[1], dimensions[1], image[1], label[1]
  134. 2    1    2    1        change to palette[2] and image[2]
  135. 3    1    2    1        change to palette[3]
  136. 4    1    4    1        change to palette[4] and image[4]
  137. 4    1    10    10        change to image[10] and label[10]
  138.  
  139.  
  140. Of course, these conventions only work if all of the programs that 
  141. touch a file do so without altering the reference numbering 
  142. scheme. If this cannot be guaranteed, you have a second solution╤
  143. to impose order on the file by means of a sorted, keyed index. This 
  144. is a good solution because it can provide random access as well as 
  145. ordered access to data; however, it adds a level of complexity to 
  146. what might otherwise be a simple sequential file organization.
  147.  
  148. Multiple References and File Compaction
  149.  
  150. Multiple references to a single data element are quite common.  
  151. The general purpose routine DFdup (see Chapter 2) generates a new 
  152. reference to data that is already pointed to by another DD.  If DFdup 
  153. is used several times, there could be several DDs that point to the 
  154. same data element.  It is important to note that when such a 
  155. multiply referenced data element is moved, the various DDs that 
  156. pointed to the data element before it was moved are not 
  157. automatically adjusted to point to the data element in its new 
  158. location.
  159.  
  160. For example, when DFaccess is called for write access, the 
  161. referenced data is copied to the end of the HDF file to allow the user 
  162. to append to that element. The original data is not moved, only 
  163. copied. If there are multiple references to that data, the old 
  164. references still point to the old data.
  165.  
  166. Consequently, compaction of a file should be done in the following 
  167. manner. Proceed through the data descriptors in order. For each 
  168. descriptor, determine whether the data has already been copied; if 
  169. not, copy the data into a new file and update its descriptor. If the 
  170. data has already been copied, as in the case of a multiple reference, 
  171. then the descriptor should be placed in the new file as a multiple 
  172. reference. Any data that no longer has a DD reference should not 
  173. be copied to the new file.
  174.  
  175. After updating elements, you may need to call DFdescriptors 
  176. again to make sure that your copy of the descriptors is up-to-date.
  177.  
  178. Of course, for most programs you will be writing, you only need to 
  179. create a completely new file, add elements to an existing file, or 
  180. read a pre-existing file. For all of these operations, consistency is 
  181. completely handled by the lower level HDF interface, even in the 
  182. case of multiple references to the same data.
  183.  
  184.